home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / libsmbclient.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-03-15  |  84.2 KB  |  2,194 lines

  1. /*=====================================================================
  2.   Unix SMB/Netbios implementation.
  3.   SMB client library API definitions
  4.   Copyright (C) Andrew Tridgell 1998
  5.   Copyright (C) Richard Sharpe 2000
  6.   Copyright (C) John Terpsra 2000
  7.   Copyright (C) Tom Jansen (Ninja ISD) 2002 
  8.   Copyright (C) Derrell Lipman 2003
  9.  
  10.    
  11.   This program is free software; you can redistribute it and/or modify
  12.   it under the terms of the GNU General Public License as published by
  13.   the Free Software Foundation; either version 2 of the License, or
  14.   (at your option) any later version.
  15.    
  16.   This program is distributed in the hope that it will be useful,
  17.   but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.   GNU General Public License for more details.
  20.    
  21.   You should have received a copy of the GNU General Public License
  22.   along with this program; if not, write to the Free Software
  23.   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  24.   =====================================================================*/
  25.  
  26. #ifndef SMBCLIENT_H_INCLUDED
  27. #define SMBCLIENT_H_INCLUDED
  28.  
  29. #ifdef __cplusplus
  30. extern "C" {
  31. #endif
  32.  
  33. /*-------------------------------------------------------------------*/
  34. /* The following are special comments to instruct DOXYGEN (automated 
  35.  * documentation tool:
  36. */
  37. /** \defgroup libsmbclient
  38. */
  39. /** \defgroup structure Data Structures Type and Constants
  40. *   \ingroup libsmbclient
  41. *   Data structures, types, and constants
  42. */
  43. /** \defgroup callback Callback function types
  44. *   \ingroup libsmbclient
  45. *   Callback functions
  46. */
  47. /** \defgroup file File Functions
  48. *   \ingroup libsmbclient
  49. *   Functions used to access individual file contents
  50. */
  51. /** \defgroup directory Directory Functions
  52. *   \ingroup libsmbclient
  53. *   Functions used to access directory entries
  54. */
  55. /** \defgroup attribute Attributes Functions
  56. *   \ingroup libsmbclient
  57. *   Functions used to view or change file and directory attributes
  58. */
  59. /** \defgroup print Print Functions
  60. *   \ingroup libsmbclient
  61. *   Functions used to access printing functionality
  62. */
  63. /** \defgroup misc Miscellaneous Functions
  64. *   \ingroup libsmbclient
  65. *   Functions that don't fit in to other categories
  66. */
  67. /*-------------------------------------------------------------------*/   
  68.  
  69. /* Make sure we have the following includes for now ... */
  70. #include <sys/types.h>
  71. #include <sys/stat.h>
  72. #include <fcntl.h>
  73. #include <utime.h>
  74.  
  75. #define SMBC_BASE_FD        10000 /* smallest file descriptor returned */
  76.  
  77. #define SMBC_WORKGROUP      1
  78. #define SMBC_SERVER         2
  79. #define SMBC_FILE_SHARE     3
  80. #define SMBC_PRINTER_SHARE  4
  81. #define SMBC_COMMS_SHARE    5
  82. #define SMBC_IPC_SHARE      6
  83. #define SMBC_DIR            7
  84. #define SMBC_FILE           8
  85. #define SMBC_LINK           9
  86.  
  87. /**@ingroup structure
  88.  * Structure that represents a directory entry.
  89.  *
  90.  */
  91. struct smbc_dirent 
  92. {
  93.     /** Type of entity.
  94.         SMBC_WORKGROUP=1,
  95.         SMBC_SERVER=2, 
  96.         SMBC_FILE_SHARE=3,
  97.         SMBC_PRINTER_SHARE=4,
  98.         SMBC_COMMS_SHARE=5,
  99.         SMBC_IPC_SHARE=6,
  100.         SMBC_DIR=7,
  101.         SMBC_FILE=8,
  102.         SMBC_LINK=9,*/ 
  103.     unsigned int smbc_type; 
  104.  
  105.     /** Length of this smbc_dirent in bytes
  106.      */
  107.     unsigned int dirlen;
  108.     /** The length of the comment string in bytes (does not include
  109.      *  null terminator)
  110.      */
  111.     unsigned int commentlen;
  112.     /** Points to the null terminated comment string 
  113.      */
  114.     char *comment;
  115.     /** The length of the name string in bytes (does not include
  116.      *  null terminator)
  117.      */
  118.     unsigned int namelen;
  119.     /** Points to the null terminated name string 
  120.      */
  121.     char name[1];
  122. };
  123.  
  124. /*
  125.  * Flags for smbc_setxattr()
  126.  *   Specify a bitwise OR of these, or 0 to add or replace as necessary
  127.  */
  128. #define SMBC_XATTR_FLAG_CREATE       0x1 /* fail if attr already exists */
  129. #define SMBC_XATTR_FLAG_REPLACE      0x2 /* fail if attr does not exist */
  130.  
  131.  
  132. /*
  133.  * Mappings of the DOS mode bits, as returned by smbc_getxattr() when the
  134.  * attribute name "system.dos_attr.mode" (or "system.dos_attr.*" or
  135.  * "system.*") is specified.
  136.  */
  137. #define SMBC_DOS_MODE_READONLY       0x01
  138. #define SMBC_DOS_MODE_HIDDEN         0x02
  139. #define SMBC_DOS_MODE_SYSTEM         0x04
  140. #define SMBC_DOS_MODE_VOLUME_ID      0x08
  141. #define SMBC_DOS_MODE_DIRECTORY      0x10
  142. #define SMBC_DOS_MODE_ARCHIVE        0x20
  143.  
  144. /*
  145.  * Valid values for the option "open_share_mode", when calling
  146.  * smbc_option_set()
  147.  */
  148. typedef enum smbc_share_mode
  149. {
  150.     SMBC_SHAREMODE_DENY_DOS     = 0,
  151.     SMBC_SHAREMODE_DENY_ALL     = 1,
  152.     SMBC_SHAREMODE_DENY_WRITE   = 2,
  153.     SMBC_SHAREMODE_DENY_READ    = 3,
  154.     SMBC_SHAREMODE_DENY_NONE    = 4,
  155.     SMBC_SHAREMODE_DENY_FCB     = 7
  156. } smbc_share_mode;
  157.  
  158.  
  159. #ifndef ENOATTR
  160. # define ENOATTR ENOENT        /* No such attribute */
  161. #endif
  162.  
  163.  
  164.  
  165.  
  166. /**@ingroup structure
  167.  * Structure that represents a print job.
  168.  *
  169.  */
  170. #ifndef _CLIENT_H
  171. struct print_job_info 
  172. {
  173.     /** numeric ID of the print job
  174.      */
  175.     unsigned short id;
  176.     
  177.     /** represents print job priority (lower numbers mean higher priority)
  178.      */
  179.     unsigned short priority;
  180.     
  181.     /** Size of the print job
  182.      */
  183.     size_t size;
  184.     
  185.     /** Name of the user that owns the print job
  186.      */
  187.     char user[128];
  188.   
  189.     /** Name of the print job. This will have no name if an anonymous print
  190.      *  file was opened. Ie smb://server/printer
  191.      */
  192.     char name[128];
  193.  
  194.     /** Time the print job was spooled
  195.      */
  196.     time_t t;
  197. };
  198. #endif /* _CLIENT_H */
  199.  
  200.  
  201. /**@ingroup structure
  202.  * Server handle 
  203.  */
  204. typedef struct _SMBCSRV  SMBCSRV;
  205.  
  206. /**@ingroup structure
  207.  * File or directory handle 
  208.  */
  209. typedef struct _SMBCFILE SMBCFILE;
  210.  
  211. /**@ingroup structure
  212.  * File or directory handle 
  213.  */
  214. typedef struct _SMBCCTX SMBCCTX;
  215.  
  216.  
  217.  
  218.  
  219.  
  220. /**@ingroup callback
  221.  * Authentication callback function type (traditional method)
  222.  * 
  223.  * Type for the the authentication function called by the library to
  224.  * obtain authentication credentals
  225.  *
  226.  * @param srv       Server being authenticated to
  227.  *
  228.  * @param shr       Share being authenticated to
  229.  *
  230.  * @param wg        Pointer to buffer containing a "hint" for the
  231.  *                  workgroup to be authenticated.  Should be filled in
  232.  *                  with the correct workgroup if the hint is wrong.
  233.  * 
  234.  * @param wglen     The size of the workgroup buffer in bytes
  235.  *
  236.  * @param un        Pointer to buffer containing a "hint" for the
  237.  *                  user name to be use for authentication. Should be
  238.  *                  filled in with the correct workgroup if the hint is
  239.  *                  wrong.
  240.  * 
  241.  * @param unlen     The size of the username buffer in bytes
  242.  *
  243.  * @param pw        Pointer to buffer containing to which password 
  244.  *                  copied
  245.  * 
  246.  * @param pwlen     The size of the password buffer in bytes
  247.  *           
  248.  */
  249. typedef void (*smbc_get_auth_data_fn)(const char *srv, 
  250.                                       const char *shr,
  251.                                       char *wg, int wglen, 
  252.                                       char *un, int unlen,
  253.                                       char *pw, int pwlen);
  254. /**@ingroup callback
  255.  * Authentication callback function type (method that includes context)
  256.  * 
  257.  * Type for the the authentication function called by the library to
  258.  * obtain authentication credentals
  259.  *
  260.  * @param c         Pointer to the smb context
  261.  *
  262.  * @param srv       Server being authenticated to
  263.  *
  264.  * @param shr       Share being authenticated to
  265.  *
  266.  * @param wg        Pointer to buffer containing a "hint" for the
  267.  *                  workgroup to be authenticated.  Should be filled in
  268.  *                  with the correct workgroup if the hint is wrong.
  269.  * 
  270.  * @param wglen     The size of the workgroup buffer in bytes
  271.  *
  272.  * @param un        Pointer to buffer containing a "hint" for the
  273.  *                  user name to be use for authentication. Should be
  274.  *                  filled in with the correct workgroup if the hint is
  275.  *                  wrong.
  276.  * 
  277.  * @param unlen     The size of the username buffer in bytes
  278.  *
  279.  * @param pw        Pointer to buffer containing to which password 
  280.  *                  copied
  281.  * 
  282.  * @param pwlen     The size of the password buffer in bytes
  283.  *           
  284.  */
  285. typedef void (*smbc_get_auth_data_with_context_fn)(SMBCCTX *c,
  286.                                                    const char *srv, 
  287.                                                    const char *shr,
  288.                                                    char *wg, int wglen, 
  289.                                                    char *un, int unlen,
  290.                                                    char *pw, int pwlen);
  291.  
  292.  
  293. /**@ingroup callback
  294.  * Print job info callback function type.
  295.  *
  296.  * @param i         pointer to print job information structure
  297.  *
  298.  */ 
  299. typedef void (*smbc_list_print_job_fn)(struct print_job_info *i);
  300.         
  301.  
  302. /**@ingroup callback
  303.  * Check if a server is still good
  304.  *
  305.  * @param c         pointer to smb context
  306.  *
  307.  * @param srv       pointer to server to check
  308.  *
  309.  * @return          0 when connection is good. 1 on error.
  310.  *
  311.  */ 
  312. typedef int (*smbc_check_server_fn)(SMBCCTX * c, SMBCSRV *srv);
  313.  
  314. /**@ingroup callback
  315.  * Remove a server if unused
  316.  *
  317.  * @param c         pointer to smb context
  318.  *
  319.  * @param srv       pointer to server to remove
  320.  *
  321.  * @return          0 on success. 1 on failure.
  322.  *
  323.  */ 
  324. typedef int (*smbc_remove_unused_server_fn)(SMBCCTX * c, SMBCSRV *srv);
  325.  
  326.  
  327. /**@ingroup callback
  328.  * Add a server to the cache system
  329.  *
  330.  * @param c         pointer to smb context
  331.  *
  332.  * @param srv       pointer to server to add
  333.  *
  334.  * @param server    server name 
  335.  *
  336.  * @param share     share name
  337.  *
  338.  * @param workgroup workgroup used to connect
  339.  *
  340.  * @param username  username used to connect
  341.  *
  342.  * @return          0 on success. 1 on failure.
  343.  *
  344.  */ 
  345. typedef int (*smbc_add_cached_srv_fn)   (SMBCCTX * c, SMBCSRV *srv, 
  346.                     const char * server, const char * share,
  347.                     const char * workgroup, const char * username);
  348.  
  349. /**@ingroup callback
  350.  * Look up a server in the cache system
  351.  *
  352.  * @param c         pointer to smb context
  353.  *
  354.  * @param server    server name to match
  355.  *
  356.  * @param share     share name to match
  357.  *
  358.  * @param workgroup workgroup to match
  359.  *
  360.  * @param username  username to match
  361.  *
  362.  * @return          pointer to SMBCSRV on success. NULL on failure.
  363.  *
  364.  */ 
  365. typedef SMBCSRV * (*smbc_get_cached_srv_fn)   (SMBCCTX * c, const char * server,
  366.                            const char * share, const char * workgroup,
  367.                                                const char * username);
  368.  
  369. /**@ingroup callback
  370.  * Check if a server is still good
  371.  *
  372.  * @param c         pointer to smb context
  373.  *
  374.  * @param srv       pointer to server to remove
  375.  *
  376.  * @return          0 when found and removed. 1 on failure.
  377.  *
  378.  */ 
  379. typedef int (*smbc_remove_cached_srv_fn)(SMBCCTX * c, SMBCSRV *srv);
  380.  
  381.  
  382. /**@ingroup callback
  383.  * Try to remove all servers from the cache system and disconnect
  384.  *
  385.  * @param c         pointer to smb context
  386.  *
  387.  * @return          0 when found and removed. 1 on failure.
  388.  *
  389.  */ 
  390. typedef int (*smbc_purge_cached_fn)     (SMBCCTX * c);
  391.  
  392.  
  393. /**@ingroup structure
  394.  * Structure that contains a client context information 
  395.  * This structure is know as SMBCCTX
  396.  */
  397. struct _SMBCCTX {
  398.     /** debug level 
  399.      */
  400.     int     debug;
  401.     
  402.     /** netbios name used for making connections
  403.      */
  404.     char * netbios_name;
  405.  
  406.     /** workgroup name used for making connections 
  407.      */
  408.     char * workgroup;
  409.  
  410.     /** username used for making connections 
  411.      */
  412.     char * user;
  413.  
  414.     /** timeout used for waiting on connections / response data (in milliseconds)
  415.      */
  416.     int timeout;
  417.  
  418.     /** callable functions for files:
  419.      * For usage and return values see the smbc_* functions
  420.      */ 
  421.     SMBCFILE * (*open)    (SMBCCTX *c, const char *fname, int flags, mode_t mode);
  422.     SMBCFILE * (*creat)   (SMBCCTX *c, const char *path, mode_t mode);
  423.     ssize_t    (*read)    (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count);
  424.     ssize_t    (*write)   (SMBCCTX *c, SMBCFILE *file, void *buf, size_t count);
  425.     int        (*unlink)  (SMBCCTX *c, const char *fname);
  426.     int        (*rename)  (SMBCCTX *ocontext, const char *oname, 
  427.                    SMBCCTX *ncontext, const char *nname);
  428.     off_t      (*lseek)   (SMBCCTX *c, SMBCFILE * file, off_t offset, int whence);
  429.     int        (*stat)    (SMBCCTX *c, const char *fname, struct stat *st);
  430.     int        (*fstat)   (SMBCCTX *c, SMBCFILE *file, struct stat *st);
  431.     int        (*close_fn) (SMBCCTX *c, SMBCFILE *file);
  432.  
  433.     /** callable functions for dirs
  434.      */ 
  435.     SMBCFILE * (*opendir) (SMBCCTX *c, const char *fname);
  436.     int        (*closedir)(SMBCCTX *c, SMBCFILE *dir);
  437.     struct smbc_dirent * (*readdir)(SMBCCTX *c, SMBCFILE *dir);
  438.     int        (*getdents)(SMBCCTX *c, SMBCFILE *dir, 
  439.                    struct smbc_dirent *dirp, int count);
  440.     int        (*mkdir)   (SMBCCTX *c, const char *fname, mode_t mode);
  441.     int        (*rmdir)   (SMBCCTX *c, const char *fname);
  442.     off_t      (*telldir) (SMBCCTX *c, SMBCFILE *dir);
  443.     int        (*lseekdir)(SMBCCTX *c, SMBCFILE *dir, off_t offset);
  444.     int        (*fstatdir)(SMBCCTX *c, SMBCFILE *dir, struct stat *st);
  445.         int        (*chmod)(SMBCCTX *c, const char *fname, mode_t mode);
  446.         int        (*utimes)(SMBCCTX *c,
  447.                              const char *fname, struct timeval *tbuf);
  448.         int        (*setxattr)(SMBCCTX *context,
  449.                                const char *fname,
  450.                                const char *name,
  451.                                const void *value,
  452.                                size_t size,
  453.                                int flags);
  454.         int        (*getxattr)(SMBCCTX *context,
  455.                                const char *fname,
  456.                                const char *name,
  457.                                const void *value,
  458.                                size_t size);
  459.         int        (*removexattr)(SMBCCTX *context,
  460.                                   const char *fname,
  461.                                   const char *name);
  462.         int        (*listxattr)(SMBCCTX *context,
  463.                                 const char *fname,
  464.                                 char *list,
  465.                                 size_t size);
  466.  
  467.     /** callable functions for printing
  468.      */ 
  469.     int        (*print_file)(SMBCCTX *c_file, const char *fname, 
  470.                  SMBCCTX *c_print, const char *printq);
  471.     SMBCFILE * (*open_print_job)(SMBCCTX *c, const char *fname);
  472.     int        (*list_print_jobs)(SMBCCTX *c, const char *fname, smbc_list_print_job_fn fn);
  473.     int        (*unlink_print_job)(SMBCCTX *c, const char *fname, int id);
  474.  
  475.  
  476.         /*
  477.         ** Callbacks
  478.         * These callbacks _always_ have to be initialized because they will
  479.         * not be checked at dereference for increased speed.
  480.         */
  481.     struct _smbc_callbacks {
  482.         /** authentication function callback: called upon auth requests
  483.          */
  484.                 smbc_get_auth_data_fn auth_fn;
  485.         
  486.         /** check if a server is still good
  487.          */
  488.         smbc_check_server_fn check_server_fn;
  489.  
  490.         /** remove a server if unused
  491.          */
  492.         smbc_remove_unused_server_fn remove_unused_server_fn;
  493.  
  494.         /** Cache subsystem
  495.          * For an example cache system see samba/source/libsmb/libsmb_cache.c
  496.          * Cache subsystem functions follow.
  497.          */
  498.  
  499.         /** server cache addition 
  500.          */
  501.         smbc_add_cached_srv_fn add_cached_srv_fn;
  502.  
  503.         /** server cache lookup 
  504.          */
  505.         smbc_get_cached_srv_fn get_cached_srv_fn;
  506.  
  507.         /** server cache removal
  508.          */
  509.         smbc_remove_cached_srv_fn remove_cached_srv_fn;
  510.         
  511.         /** server cache purging, try to remove all cached servers (disconnect)
  512.          */
  513.         smbc_purge_cached_fn purge_cached_fn;
  514.     } callbacks;
  515.  
  516.  
  517.     /** Space to store private data of the server cache.
  518.      */
  519.     struct smbc_server_cache * server_cache;
  520.  
  521.     int flags;
  522.     
  523.         /** user options selections that apply to this session
  524.          */
  525.         struct _smbc_options {
  526.  
  527.                 /*
  528.                  * From how many local master browsers should the list of
  529.                  * workgroups be retrieved?  It can take up to 12 minutes or
  530.                  * longer after a server becomes a local master browser, for
  531.                  * it to have the entire browse list (the list of
  532.                  * workgroups/domains) from an entire network.  Since a client
  533.                  * never knows which local master browser will be found first,
  534.                  * the one which is found first and used to retrieve a browse
  535.                  * list may have an incomplete or empty browse list.  By
  536.                  * requesting the browse list from multiple local master
  537.                  * browsers, a more complete list can be generated.  For small
  538.                  * networks (few workgroups), it is recommended that this
  539.                  * value be set to 0, causing the browse lists from all found
  540.                  * local master browsers to be retrieved and merged.  For
  541.                  * networks with many workgroups, a suitable value for this
  542.                  * variable is probably somewhere around 3. (Default: 3).
  543.                  */
  544.                 int browse_max_lmb_count;
  545.  
  546.                 /*
  547.                  * There is a difference in the desired return strings from
  548.                  * smbc_readdir() depending upon whether the filenames are to
  549.                  * be displayed to the user, or whether they are to be
  550.                  * appended to the path name passed to smbc_opendir() to call
  551.                  * a further smbc_ function (e.g. open the file with
  552.                  * smbc_open()).  In the former case, the filename should be
  553.                  * in "human readable" form.  In the latter case, the smbc_
  554.                  * functions expect a URL which must be url-encoded.  Those
  555.                  * functions decode the URL.  If, for example, smbc_readdir()
  556.                  * returned a file name of "abc%20def.txt", passing a path
  557.                  * with this file name attached to smbc_open() would cause
  558.                  * smbc_open to attempt to open the file "abc def.txt" since
  559.                  * the %20 is decoded into a space.
  560.                  *
  561.                  * Set this option to True if the names returned by
  562.                  * smbc_readdir() should be url-encoded such that they can be
  563.                  * passed back to another smbc_ call.  Set it to False if the
  564.                  * names returned by smbc_readdir() are to be presented to the
  565.                  * user.
  566.                  *
  567.                  * For backwards compatibility, this option defaults to False.
  568.                  */
  569.                 int urlencode_readdir_entries;
  570.  
  571.                 /*
  572.                  * Some Windows versions appear to have a limit to the number
  573.                  * of concurrent SESSIONs and/or TREE CONNECTions.  In
  574.                  * one-shot programs (i.e. the program runs and then quickly
  575.                  * ends, thereby shutting down all connections), it is
  576.                  * probably reasonable to establish a new connection for each
  577.                  * share.  In long-running applications, the limitation can be
  578.                  * avoided by using only a single connection to each server,
  579.                  * and issuing a new TREE CONNECT when the share is accessed.
  580.                  */
  581.                 int one_share_per_server;
  582.         } options;
  583.     
  584.     /** INTERNAL DATA
  585.      * do _NOT_ touch this from your program !
  586.      */
  587.     struct smbc_internal_data * internal;
  588. };
  589.  
  590. /* Flags for SMBCCTX->flags */
  591. #define SMB_CTX_FLAG_USE_KERBEROS (1 << 0)
  592. #define SMB_CTX_FLAG_FALLBACK_AFTER_KERBEROS (1 << 1)
  593. #define SMBCCTX_FLAG_NO_AUTO_ANONYMOUS_LOGON (1 << 2) /* don't try to do automatic anon login */
  594.  
  595. /**@ingroup misc
  596.  * Create a new SBMCCTX (a context).
  597.  *
  598.  * Must be called before the context is passed to smbc_context_init()
  599.  *
  600.  * @return          The given SMBCCTX pointer on success, NULL on error with errno set:
  601.  *                  - ENOMEM Out of memory
  602.  *
  603.  * @see             smbc_free_context(), smbc_init_context()
  604.  *
  605.  * @note            Do not forget to smbc_init_context() the returned SMBCCTX pointer !
  606.  */
  607. SMBCCTX * smbc_new_context(void);
  608.  
  609. /**@ingroup misc
  610.  * Delete a SBMCCTX (a context) acquired from smbc_new_context().
  611.  *
  612.  * The context will be deleted if possible.
  613.  *
  614.  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
  615.  *
  616.  * @param shutdown_ctx   If 1, all connections and files will be closed even if they are busy.
  617.  *
  618.  *
  619.  * @return          Returns 0 on succes. Returns 1 on failure with errno set:
  620.  *                  - EBUSY Server connections are still used, Files are open or cache 
  621.  *                          could not be purged
  622.  *                  - EBADF context == NULL
  623.  *
  624.  * @see             smbc_new_context()
  625.  *
  626.  * @note            It is advised to clean up all the contexts with shutdown_ctx set to 1
  627.  *                  just before exit()'ing. When shutdown_ctx is 0, this function can be
  628.  *                  use in periodical cleanup functions for example.
  629.  */
  630. int smbc_free_context(SMBCCTX * context, int shutdown_ctx);
  631.  
  632.  
  633. /**@ingroup misc
  634.  * Each time the context structure is changed, we have binary backward
  635.  * compatibility issues.  Instead of modifying the public portions of the
  636.  * context structure to add new options, instead, we put them in the internal
  637.  * portion of the context structure and provide a set function for these new
  638.  * options.
  639.  *
  640.  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
  641.  *
  642.  * @param option_name
  643.  *                  The name of the option for which the value is to be set
  644.  *
  645.  * @param option_value
  646.  *                  The new value of the option being set
  647.  *
  648.  */
  649. void
  650. smbc_option_set(SMBCCTX *context,
  651.                 char *option_name,
  652.                 ... /* option_value */);
  653. /*
  654.  * Retrieve the current value of an option
  655.  *
  656.  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
  657.  *
  658.  * @param option_name
  659.  *                  The name of the option for which the value is to be
  660.  *                  retrieved
  661.  *
  662.  * @return          The value of the specified option.
  663.  */
  664. void *
  665. smbc_option_get(SMBCCTX *context,
  666.                 char *option_name);
  667.  
  668. /**@ingroup misc
  669.  * Initialize a SBMCCTX (a context).
  670.  *
  671.  * Must be called before using any SMBCCTX API function
  672.  *
  673.  * @param context   A pointer to a SMBCCTX obtained from smbc_new_context()
  674.  *
  675.  * @return          A pointer to the given SMBCCTX on success,
  676.  *                  NULL on error with errno set:
  677.  *                  - EBADF  NULL context given
  678.  *                  - ENOMEM Out of memory
  679.  *                  - ENOENT The smb.conf file would not load
  680.  *
  681.  * @see             smbc_new_context()
  682.  *
  683.  * @note            my_context = smbc_init_context(smbc_new_context())
  684.  *                  is perfectly safe, but it might leak memory on
  685.  *                  smbc_context_init() failure. Avoid this.
  686.  *                  You'll have to call smbc_free_context() yourself
  687.  *                  on failure.  
  688.  */
  689.  
  690. SMBCCTX * smbc_init_context(SMBCCTX * context);
  691.  
  692. /**@ingroup misc
  693.  * Initialize the samba client library.
  694.  *
  695.  * Must be called before using any of the smbclient API function
  696.  *  
  697.  * @param fn        The function that will be called to obtaion 
  698.  *                  authentication credentials.
  699.  *
  700.  * @param debug     Allows caller to set the debug level. Can be
  701.  *                  changed in smb.conf file. Allows caller to set
  702.  *                  debugging if no smb.conf.
  703.  *   
  704.  * @return          0 on success, < 0 on error with errno set:
  705.  *                  - ENOMEM Out of memory
  706.  *                  - ENOENT The smb.conf file would not load
  707.  *
  708.  */
  709.  
  710. int smbc_init(smbc_get_auth_data_fn fn, int debug);
  711.  
  712. /**@ingroup misc
  713.  * Set or retrieve the compatibility library's context pointer
  714.  *
  715.  * @param context   New context to use, or NULL.  If a new context is provided,
  716.  *                  it must have allocated with smbc_new_context() and
  717.  *                  initialized with smbc_init_context(), followed, optionally,
  718.  *                  by some manual changes to some of the non-internal fields.
  719.  *
  720.  * @return          The old context.
  721.  *
  722.  * @see             smbc_new_context(), smbc_init_context(), smbc_init()
  723.  *
  724.  * @note            This function may be called prior to smbc_init() to force
  725.  *                  use of the next context without any internal calls to
  726.  *                  smbc_new_context() or smbc_init_context().  It may also
  727.  *                  be called after smbc_init() has already called those two
  728.  *                  functions, to replace the existing context with a new one.
  729.  *                  Care should be taken, in this latter case, to ensure that
  730.  *                  the server cache and any data allocated by the
  731.  *                  authentication functions have been freed, if necessary.
  732.  */
  733.  
  734. SMBCCTX * smbc_set_context(SMBCCTX * new_context);
  735.  
  736. /**@ingroup file
  737.  * Open a file on an SMB server.
  738.  *
  739.  * @param furl      The smb url of the file to be opened. 
  740.  *
  741.  * @param flags     Is one of O_RDONLY, O_WRONLY or O_RDWR which 
  742.  *                  request opening  the  file  read-only,write-only
  743.  *                  or read/write. flags may also be bitwise-or'd with
  744.  *                  one or  more of  the following: 
  745.  *                  O_CREAT - If the file does not exist it will be 
  746.  *                  created.
  747.  *                  O_EXCL - When  used with O_CREAT, if the file 
  748.  *                  already exists it is an error and the open will 
  749.  *                  fail. 
  750.  *                  O_TRUNC - If the file already exists it will be
  751.  *                  truncated.
  752.  *                  O_APPEND The  file  is  opened  in  append mode 
  753.  *
  754.  * @param mode      mode specifies the permissions to use if a new 
  755.  *                  file is created.  It  is  modified  by  the 
  756.  *                  process's umask in the usual way: the permissions
  757.  *                  of the created file are (mode & ~umask) 
  758.  *
  759.  *                  Not currently use, but there for future use.
  760.  *                  We will map this to SYSTEM, HIDDEN, etc bits
  761.  *                  that reverses the mapping that smbc_fstat does.
  762.  *
  763.  * @return          Valid file handle, < 0 on error with errno set:
  764.  *                  - ENOMEM  Out of memory
  765.  *                  - EINVAL if an invalid parameter passed, like no 
  766.  *                  file, or smbc_init not called.
  767.  *                  - EEXIST  pathname already exists and O_CREAT and 
  768.  *                  O_EXCL were used.
  769.  *                  - EISDIR  pathname  refers  to  a  directory  and  
  770.  *                  the access requested involved writing.
  771.  *                  - EACCES  The requested access to the file is not 
  772.  *                  allowed 
  773.  *                  - ENODEV The requested share does not exist
  774.  *                  - ENOTDIR A file on the path is not a directory
  775.  *                  - ENOENT  A directory component in pathname does 
  776.  *                  not exist.
  777.  *
  778.  * @see             smbc_creat()
  779.  *
  780.  * @note            This call uses an underlying routine that may create
  781.  *                  a new connection to the server specified in the URL.
  782.  *                  If the credentials supplied in the URL, or via the
  783.  *                  auth_fn in the smbc_init call, fail, this call will
  784.  *                  try again with an empty username and password. This 
  785.  *                  often gets mapped to the guest account on some machines.
  786.  */
  787.  
  788. int smbc_open(const char *furl, int flags, mode_t mode);
  789.  
  790. /**@ingroup file
  791.  * Create a file on an SMB server.
  792.  *
  793.  * Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC 
  794.  *   
  795.  * @param furl      The smb url of the file to be created
  796.  *  
  797.  * @param mode      mode specifies the permissions to use if  a  new  
  798.  *                  file is created.  It  is  modified  by  the 
  799.  *                  process's umask in the usual way: the permissions
  800.  *                  of the created file are (mode & ~umask)
  801.  *
  802.  *                  NOTE, the above is not true. We are dealing with 
  803.  *                  an SMB server, which has no concept of a umask!
  804.  *      
  805.  * @return          Valid file handle, < 0 on error with errno set:
  806.  *                  - ENOMEM  Out of memory
  807.  *                  - EINVAL if an invalid parameter passed, like no 
  808.  *                  file, or smbc_init not called.
  809.  *                  - EEXIST  pathname already exists and O_CREAT and
  810.  *                  O_EXCL were used.
  811.  *                  - EISDIR  pathname  refers  to  a  directory  and
  812.  *                  the access requested involved writing.
  813.  *                  - EACCES  The requested access to the file is not
  814.  *                  allowed 
  815.  *                  - ENOENT  A directory component in pathname does 
  816.  *                  not exist.
  817.  *                  - ENODEV The requested share does not exist.
  818.  * @see             smbc_open()
  819.  *
  820.  */
  821.  
  822. int smbc_creat(const char *furl, mode_t mode);
  823.  
  824. /**@ingroup file
  825.  * Read from a file using an opened file handle.
  826.  *
  827.  * @param fd        Open file handle from smbc_open() or smbc_creat()
  828.  *
  829.  * @param buf       Pointer to buffer to recieve read data
  830.  *
  831.  * @param bufsize   Size of buf in bytes
  832.  *
  833.  * @return          Number of bytes read, < 0 on error with errno set:
  834.  *                  - EISDIR fd refers to a directory
  835.  *                  - EBADF  fd  is  not  a valid file descriptor or 
  836.  *                  is not open for reading.
  837.  *                  - EINVAL fd is attached to an object which is 
  838.  *                  unsuitable for reading, or no buffer passed or
  839.  *            smbc_init not called.
  840.  *
  841.  * @see             smbc_open(), smbc_write()
  842.  *
  843.  */
  844. ssize_t smbc_read(int fd, void *buf, size_t bufsize);
  845.  
  846.  
  847. /**@ingroup file
  848.  * Write to a file using an opened file handle.
  849.  *
  850.  * @param fd        Open file handle from smbc_open() or smbc_creat()
  851.  *
  852.  * @param buf       Pointer to buffer to recieve read data
  853.  *
  854.  * @param bufsize   Size of buf in bytes
  855.  *
  856.  * @return          Number of bytes written, < 0 on error with errno set:
  857.  *                  - EISDIR fd refers to a directory.
  858.  *                  - EBADF  fd  is  not  a valid file descriptor or 
  859.  *                  is not open for reading.
  860.  *                  - EINVAL fd is attached to an object which is 
  861.  *                  unsuitable for reading, or no buffer passed or
  862.  *            smbc_init not called.
  863.  *
  864.  * @see             smbc_open(), smbc_read()
  865.  *
  866.  */
  867. ssize_t smbc_write(int fd, void *buf, size_t bufsize);
  868.  
  869.  
  870. /**@ingroup file
  871.  * Seek to a specific location in a file.
  872.  *
  873.  * @param fd        Open file handle from smbc_open() or smbc_creat()
  874.  * 
  875.  * @param offset    Offset in bytes from whence
  876.  * 
  877.  * @param whence    A location in the file:
  878.  *                  - SEEK_SET The offset is set to offset bytes from
  879.  *                  the beginning of the file
  880.  *                  - SEEK_CUR The offset is set to current location 
  881.  *                  plus offset bytes.
  882.  *                  - SEEK_END The offset is set to the size of the 
  883.  *                  file plus offset bytes.
  884.  *
  885.  * @return          Upon successful completion, lseek returns the 
  886.  *                  resulting offset location as measured in bytes 
  887.  *                  from the beginning  of the file. Otherwise, a value
  888.  *                  of (off_t)-1 is returned and errno is set to 
  889.  *                  indicate the error:
  890.  *                  - EBADF  Fildes is not an open file descriptor.
  891.  *                  - EINVAL Whence is not a proper value or smbc_init
  892.  *              not called.
  893.  *
  894.  * @todo Are all the whence values really supported?
  895.  * 
  896.  * @todo Are errno values complete and correct?
  897.  */
  898. off_t smbc_lseek(int fd, off_t offset, int whence);
  899.  
  900.  
  901. /**@ingroup file
  902.  * Close an open file handle.
  903.  *
  904.  * @param fd        The file handle to close
  905.  *
  906.  * @return          0 on success, < 0 on error with errno set:
  907.  *                  - EBADF  fd isn't a valid open file descriptor
  908.  *                  - EINVAL smbc_init() failed or has not been called
  909.  *
  910.  * @see             smbc_open(), smbc_creat()
  911.  */
  912. int smbc_close(int fd);
  913.  
  914.  
  915. /**@ingroup directory
  916.  * Unlink (delete) a file or directory.
  917.  *
  918.  * @param furl      The smb url of the file to delete
  919.  *
  920.  * @return          0 on success, < 0 on error with errno set:
  921.  *                  - EACCES or EPERM Write  access  to the directory 
  922.  *                  containing pathname is not allowed or one  
  923.  *                  of  the  directories in pathname did not allow
  924.  *                  search (execute) permission
  925.  *                  - ENOENT A directory component in pathname does
  926.  *                  not exist
  927.  *                  - EINVAL NULL was passed in the file param or
  928.  *              smbc_init not called.
  929.  *                  - EACCES You do not have access to the file
  930.  *                  - ENOMEM Insufficient kernel memory was available
  931.  *
  932.  * @see             smbc_rmdir()s
  933.  *
  934.  * @todo Are errno values complete and correct?
  935.  */
  936. int smbc_unlink(const char *furl);
  937.  
  938.  
  939. /**@ingroup directory
  940.  * Rename or move a file or directory.
  941.  * 
  942.  * @param ourl      The original smb url (source url) of file or 
  943.  *                  directory to be moved
  944.  * 
  945.  * @param nurl      The new smb url (destination url) of the file
  946.  *                  or directory after the move.  Currently nurl must
  947.  *                  be on the same share as ourl.
  948.  *
  949.  * @return          0 on success, < 0 on error with errno set:
  950.  *                  - EISDIR nurl is an existing directory, but ourl is
  951.  *                  not a directory.
  952.  *                  - EEXIST nurl is  a  non-empty directory, 
  953.  *                  i.e., contains entries other than "." and ".."
  954.  *                  - EINVAL The  new  url  contained  a path prefix 
  955.  *                  of the old, or, more generally, an  attempt was
  956.  *                  made  to make a directory a subdirectory of itself
  957.  *            or smbc_init not called.
  958.  *                  - ENOTDIR A component used as a directory in ourl 
  959.  *                  or nurl path is not, in fact, a directory.  Or, 
  960.  *                  ourl  is a directory, and newpath exists but is not
  961.  *                  a directory.
  962.  *                  - EACCES or EPERM Write access to the directory 
  963.  *                  containing ourl or nurl is not allowed for the 
  964.  *                  process's effective uid,  or  one of the 
  965.  *                  directories in ourl or nurl did not allow search
  966.  *                  (execute) permission,  or ourl  was  a  directory
  967.  *                  and did not allow write permission.
  968.  *                  - ENOENT A  directory component in ourl or nurl 
  969.  *                  does not exist.
  970.  *                  - EXDEV Rename across shares not supported.
  971.  *                  - ENOMEM Insufficient kernel memory was available.
  972.  *                  - EEXIST The target file, nurl, already exists.
  973.  *
  974.  *
  975.  * @todo Are we going to support copying when urls are not on the same
  976.  *       share?  I say no... NOTE. I agree for the moment.
  977.  *
  978.  */
  979. int smbc_rename(const char *ourl, const char *nurl);
  980.  
  981.  
  982. /**@ingroup directory
  983.  * Open a directory used to obtain directory entries.
  984.  *
  985.  * @param durl      The smb url of the directory to open
  986.  *
  987.  * @return          Valid directory handle. < 0 on error with errno set:
  988.  *                  - EACCES Permission denied.
  989.  *                  - EINVAL A NULL file/URL was passed, or the URL would
  990.  *                  not parse, or was of incorrect form or smbc_init not
  991.  *                  called.
  992.  *                  - ENOENT durl does not exist, or name is an 
  993.  *                  - ENOMEM Insufficient memory to complete the 
  994.  *                  operation.                              
  995.  *                  - ENOTDIR name is not a directory.
  996.  *                  - EPERM the workgroup could not be found.
  997.  *                  - ENODEV the workgroup or server could not be found.
  998.  *
  999.  * @see             smbc_getdents(), smbc_readdir(), smbc_closedir()
  1000.  *
  1001.  */
  1002. int smbc_opendir(const char *durl);
  1003.  
  1004.  
  1005. /**@ingroup directory
  1006.  * Close a directory handle opened by smbc_opendir().
  1007.  *
  1008.  * @param dh        Directory handle to close
  1009.  *
  1010.  * @return          0 on success, < 0 on error with errno set:
  1011.  *                  - EBADF dh is an invalid directory handle
  1012.  *
  1013.  * @see             smbc_opendir()
  1014.  */
  1015. int smbc_closedir(int dh);
  1016.  
  1017.  
  1018. /**@ingroup directory
  1019.  * Get multiple directory entries.
  1020.  *
  1021.  * smbc_getdents() reads as many dirent structures from the an open 
  1022.  * directory handle into a specified memory area as will fit.
  1023.  *
  1024.  * @param dh        Valid directory as returned by smbc_opendir()
  1025.  *
  1026.  * @param dirp      pointer to buffer that will receive the directory
  1027.  *                  entries.
  1028.  * 
  1029.  * @param count     The size of the dirp buffer in bytes
  1030.  *
  1031.  * @returns         If any dirents returned, return will indicate the
  1032.  *                  total size. If there were no more dirents available,
  1033.  *                  0 is returned. < 0 indicates an error.
  1034.  *                  - EBADF  Invalid directory handle
  1035.  *                  - EINVAL Result buffer is too small or smbc_init
  1036.  *            not called.
  1037.  *                  - ENOENT No such directory.
  1038.  * @see             , smbc_dirent, smbc_readdir(), smbc_open()
  1039.  *
  1040.  * @todo Are errno values complete and correct?
  1041.  *
  1042.  * @todo Add example code so people know how to parse buffers.
  1043.  */
  1044. int smbc_getdents(unsigned int dh, struct smbc_dirent *dirp, int count);
  1045.  
  1046.  
  1047. /**@ingroup directory
  1048.  * Get a single directory entry.
  1049.  *
  1050.  * @param dh        Valid directory as returned by smbc_opendir()
  1051.  *
  1052.  * @return          A pointer to a smbc_dirent structure, or NULL if an
  1053.  *                  error occurs or end-of-directory is reached:
  1054.  *                  - EBADF Invalid directory handle
  1055.  *                  - EINVAL smbc_init() failed or has not been called
  1056.  *
  1057.  * @see             smbc_dirent, smbc_getdents(), smbc_open()
  1058.  */
  1059. struct smbc_dirent* smbc_readdir(unsigned int dh);
  1060.  
  1061.  
  1062. /**@ingroup directory
  1063.  * Get the current directory offset.
  1064.  *
  1065.  * smbc_telldir() may be used in conjunction with smbc_readdir() and
  1066.  * smbc_lseekdir().
  1067.  *
  1068.  * @param dh        Valid directory as returned by smbc_opendir()
  1069.  *
  1070.  * @return          The current location in the directory stream or -1
  1071.  *                  if an error occur.  The current location is not
  1072.  *                  an offset. Becuase of the implementation, it is a 
  1073.  *                  handle that allows the library to find the entry
  1074.  *                  later.
  1075.  *                  - EBADF dh is not a valid directory handle
  1076.  *                  - EINVAL smbc_init() failed or has not been called
  1077.  *                  - ENOTDIR if dh is not a directory
  1078.  *
  1079.  * @see             smbc_readdir()
  1080.  *
  1081.  */
  1082. off_t smbc_telldir(int dh);
  1083.  
  1084.  
  1085. /**@ingroup directory
  1086.  * lseek on directories.
  1087.  *
  1088.  * smbc_lseekdir() may be used in conjunction with smbc_readdir() and
  1089.  * smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))
  1090.  *
  1091.  * @param fd        Valid directory as returned by smbc_opendir()
  1092.  * 
  1093.  * @param offset    The offset (as returned by smbc_telldir). Can be
  1094.  *                  NULL, in which case we will rewind
  1095.  *
  1096.  * @return          0 on success, -1 on failure
  1097.  *                  - EBADF dh is not a valid directory handle
  1098.  *                  - ENOTDIR if dh is not a directory
  1099.  *                  - EINVAL offset did not refer to a valid dirent or
  1100.  *              smbc_init not called.
  1101.  *
  1102.  * @see             smbc_telldir()
  1103.  *
  1104.  *
  1105.  * @todo In what does the reture and errno values mean?
  1106.  */
  1107. int smbc_lseekdir(int fd, off_t offset);
  1108.  
  1109. /**@ingroup directory
  1110.  * Create a directory.
  1111.  *
  1112.  * @param durl      The url of the directory to create
  1113.  *
  1114.  * @param mode      Specifies  the  permissions to use. It is modified
  1115.  *                  by the process's umask in the usual way: the 
  1116.  *                  permissions of the created file are (mode & ~umask).
  1117.  * 
  1118.  * @return          0 on success, < 0 on error with errno set:
  1119.  *                  - EEXIST directory url already exists
  1120.  *                  - EACCES The parent directory does not allow write
  1121.  *                  permission to the process, or one of the directories
  1122.  *                  - ENOENT A directory component in pathname does not
  1123.  *                  exist.
  1124.  *                  - EINVAL NULL durl passed or smbc_init not called.
  1125.  *                  - ENOMEM Insufficient memory was available.
  1126.  *
  1127.  * @see             smbc_rmdir()
  1128.  *
  1129.  */
  1130. int smbc_mkdir(const char *durl, mode_t mode);
  1131.  
  1132.  
  1133. /**@ingroup directory
  1134.  * Remove a directory.
  1135.  * 
  1136.  * @param durl      The smb url of the directory to remove
  1137.  *
  1138.  * @return          0 on success, < 0 on error with errno set:
  1139.  *                  - EACCES or EPERM Write access to the directory
  1140.  *                  containing pathname was not allowed.
  1141.  *                  - EINVAL durl is NULL or smbc_init not called.
  1142.  *                  - ENOENT A directory component in pathname does not
  1143.  *                  exist.
  1144.  *                  - ENOTEMPTY directory contains entries.
  1145.  *                  - ENOMEM Insufficient kernel memory was available.
  1146.  *
  1147.  * @see             smbc_mkdir(), smbc_unlink() 
  1148.  *
  1149.  * @todo Are errno values complete and correct?
  1150.  */
  1151. int smbc_rmdir(const char *durl);
  1152.  
  1153.  
  1154. /**@ingroup attribute
  1155.  * Get information about a file or directory.
  1156.  *
  1157.  * @param url       The smb url to get information for
  1158.  *
  1159.  * @param st        pointer to a buffer that will be filled with 
  1160.  *                  standard Unix struct stat information.
  1161.  *
  1162.  * @return          0 on success, < 0 on error with errno set:
  1163.  *                  - ENOENT A component of the path file_name does not
  1164.  *                  exist.
  1165.  *                  - EINVAL a NULL url was passed or smbc_init not called.
  1166.  *                  - EACCES Permission denied.
  1167.  *                  - ENOMEM Out of memory
  1168.  *                  - ENOTDIR The target dir, url, is not a directory.
  1169.  *
  1170.  * @see             Unix stat()
  1171.  *
  1172.  */
  1173. int smbc_stat(const char *url, struct stat *st);
  1174.  
  1175.  
  1176. /**@ingroup attribute
  1177.  * Get file information via an file descriptor.
  1178.  * 
  1179.  * @param fd        Open file handle from smbc_open() or smbc_creat()
  1180.  *
  1181.  * @param st        pointer to a buffer that will be filled with 
  1182.  *                  standard Unix struct stat information.
  1183.  * 
  1184.  * @return          EBADF  filedes is bad.
  1185.  *                  - EACCES Permission denied.
  1186.  *                  - EBADF fd is not a valid file descriptor
  1187.  *                  - EINVAL Problems occurred in the underlying routines
  1188.  *              or smbc_init not called.
  1189.  *                  - ENOMEM Out of memory
  1190.  *
  1191.  * @see             smbc_stat(), Unix stat()
  1192.  *
  1193.  */
  1194. int smbc_fstat(int fd, struct stat *st);
  1195.  
  1196.  
  1197. /**@ingroup attribue
  1198.  * Change the ownership of a file or directory.
  1199.  *
  1200.  * @param url       The smb url of the file or directory to change 
  1201.  *                  ownership of.
  1202.  *
  1203.  * @param owner     I have no idea?
  1204.  *
  1205.  * @param group     I have not idea?
  1206.  *
  1207.  * @return          0 on success, < 0 on error with errno set:
  1208.  *                  - EPERM  The effective UID does not match the owner
  1209.  *                  of the file, and is not zero; or the owner or group
  1210.  *                  were specified incorrectly.
  1211.  *                  - ENOENT The file does not exist.
  1212.  *                  - ENOMEM Insufficient was available.
  1213.  *                  - ENOENT file or directory does not exist
  1214.  *
  1215.  * @todo Are we actually going to be able to implement this function
  1216.  *
  1217.  * @todo How do we abstract owner and group uid and gid?
  1218.  *
  1219.  */
  1220. int smbc_chown(const char *url, uid_t owner, gid_t group);
  1221.  
  1222.  
  1223. /**@ingroup attribute
  1224.  * Change the permissions of a file.
  1225.  *
  1226.  * @param url       The smb url of the file or directory to change
  1227.  *                  permissions of
  1228.  * 
  1229.  * @param mode      The permissions to set:
  1230.  *                  - Put good explaination of permissions here!
  1231.  *
  1232.  * @return          0 on success, < 0 on error with errno set:
  1233.  *                  - EPERM  The effective UID does not match the owner
  1234.  *                  of the file, and is not zero
  1235.  *                  - ENOENT The file does not exist.
  1236.  *                  - ENOMEM Insufficient was available.
  1237.  *                  - ENOENT file or directory does not exist
  1238.  *
  1239.  * @todo Actually implement this fuction?
  1240.  *
  1241.  * @todo Are errno values complete and correct?
  1242.  */
  1243. int smbc_chmod(const char *url, mode_t mode);
  1244.  
  1245. /**@ingroup attribute
  1246.  * Change the last modification time on a file
  1247.  *
  1248.  * @param url       The smb url of the file or directory to change
  1249.  *                  the modification time of
  1250.  * 
  1251.  * @param tbuf      A timeval structure which contains the desired
  1252.  *                  modification time.  NOTE: Only the tv_sec field is
  1253.  *                  used.  The tv_usec (microseconds) portion is ignored.
  1254.  *
  1255.  * @return          0 on success, < 0 on error with errno set:
  1256.  *                  - EINVAL The client library is not properly initialized
  1257.  *                  - EPERM  Permission was denied.
  1258.  *
  1259.  */
  1260. int smbc_utimes(const char *url, struct timeval *tbuf);
  1261.  
  1262. #ifdef HAVE_UTIME_H
  1263. /**@ingroup attribute
  1264.  * Change the last modification time on a file
  1265.  *
  1266.  * @param url       The smb url of the file or directory to change
  1267.  *                  the modification time of
  1268.  * 
  1269.  * @param utbuf     A utimebuf structure which contains the desired
  1270.  *                  modification time.  NOTE: Although the structure contains
  1271.  *                  an access time as well, the access time value is ignored.
  1272.  *
  1273.  * @return          0 on success, < 0 on error with errno set:
  1274.  *                  - EINVAL The client library is not properly initialized
  1275.  *                  - ENOMEM No memory was available for internal needs
  1276.  *                  - EPERM  Permission was denied.
  1277.  *
  1278.  */
  1279. int smbc_utime(const char *fname, struct utimbuf *utbuf);
  1280. #endif
  1281.  
  1282. /**@ingroup attribute
  1283.  * Set extended attributes for a file.  This is used for modifying a file's
  1284.  * security descriptor (i.e. owner, group, and access control list)
  1285.  *
  1286.  * @param url       The smb url of the file or directory to set extended
  1287.  *                  attributes for.
  1288.  * 
  1289.  * @param name      The name of an attribute to be changed.  Names are of
  1290.  *                  one of the following forms:
  1291.  *
  1292.  *                     system.nt_sec_desc.<attribute name>
  1293.  *                     system.nt_sec_desc.*
  1294.  *                     system.nt_sec_desc.*+
  1295.  *
  1296.  *                  where <attribute name> is one of:
  1297.  *
  1298.  *                     revision
  1299.  *                     owner
  1300.  *                     owner+
  1301.  *                     group
  1302.  *                     group+
  1303.  *                     acl:<name or sid>
  1304.  *                     acl+:<name or sid>
  1305.  *
  1306.  *                  In the forms "system.nt_sec_desc.*" and
  1307.  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
  1308.  *                  literal, i.e. the string is provided exactly as shown, and
  1309.  *                  the value parameter should contain a complete security
  1310.  *                  descriptor with name:value pairs separated by tabs,
  1311.  *                  commas, or newlines (not spaces!).
  1312.  *
  1313.  *                  The plus sign ('+') indicates that SIDs should be mapped
  1314.  *                  to names.  Without the plus sign, SIDs are not mapped;
  1315.  *                  rather they are simply converted to a string format.
  1316.  *
  1317.  * @param value     The value to be assigned to the specified attribute name.
  1318.  *                  This buffer should contain only the attribute value if the
  1319.  *                  name was of the "system.nt_sec_desc.<attribute_name>"
  1320.  *                  form.  If the name was of the "system.nt_sec_desc.*" form
  1321.  *                  then a complete security descriptor, with name:value pairs
  1322.  *                  separated by tabs, commas, or newlines (not spaces!),
  1323.  *                  should be provided in this value buffer.  A complete
  1324.  *                  security descriptor will contain one or more entries
  1325.  *                  selected from the following:
  1326.  *
  1327.  *                    REVISION:<revision number>
  1328.  *                    OWNER:<sid or name>
  1329.  *                    GROUP:<sid or name>
  1330.  *                    ACL:<sid or name>:<type>/<flags>/<mask>
  1331.  *
  1332.  *                  The  revision of the ACL specifies the internal Windows NT
  1333.  *                  ACL revision for the security descriptor. If not specified
  1334.  *                  it defaults to  1.  Using values other than 1 may cause
  1335.  *                  strange behaviour.
  1336.  *
  1337.  *                  The owner and group specify the owner and group sids for
  1338.  *                  the object. If the attribute name (either '*+' with a
  1339.  *                  complete security descriptor, or individual 'owner+' or
  1340.  *                  'group+' attribute names) ended with a plus sign, the
  1341.  *                  specified name is resolved to a SID value, using the
  1342.  *                  server on which the file or directory resides.  Otherwise,
  1343.  *                  the value should be provided in SID-printable format as
  1344.  *                  S-1-x-y-z, and is used directly.  The <sid or name>
  1345.  *                  associated with the ACL: attribute should be provided
  1346.  *                  similarly.
  1347.  *
  1348.  * @param size      The number of the bytes of data in the value buffer
  1349.  *
  1350.  * @param flags     A bit-wise OR of zero or more of the following:
  1351.  *                    SMBC_XATTR_FLAG_CREATE -
  1352.  *                      fail if the named attribute already exists
  1353.  *                    SMBC_XATTR_FLAG_REPLACE -
  1354.  *                      fail if the attribute does not already exist
  1355.  *
  1356.  *                  If neither flag is specified, the specified attributes
  1357.  *                  will be added or replace existing attributes of the same
  1358.  *                  name, as necessary.
  1359.  *
  1360.  * @return          0 on success, < 0 on error with errno set:
  1361.  *                  - EINVAL  The client library is not properly initialized
  1362.  *                            or one of the parameters is not of a correct
  1363.  *                            form
  1364.  *                  - ENOMEM No memory was available for internal needs
  1365.  *                  - EEXIST  If the attribute already exists and the flag
  1366.  *                            SMBC_XATTR_FLAG_CREAT was specified
  1367.  *                  - ENOATTR If the attribute does not exist and the flag
  1368.  *                            SMBC_XATTR_FLAG_REPLACE was specified
  1369.  *                  - EPERM   Permission was denied.
  1370.  *                  - ENOTSUP The referenced file system does not support
  1371.  *                            extended attributes
  1372.  *
  1373.  * @note            Attribute names are compared in a case-insensitive
  1374.  *                  fashion.  All of the following are equivalent, although
  1375.  *                  the all-lower-case name is the preferred format:
  1376.  *                    system.nt_sec_desc.owner
  1377.  *                    SYSTEM.NT_SEC_DESC.OWNER
  1378.  *                    sYsTeM.nt_sEc_desc.owNER
  1379.  *
  1380.  */
  1381. int smbc_setxattr(const char *url,
  1382.                   const char *name,
  1383.                   const void *value,
  1384.                   size_t size,
  1385.                   int flags);
  1386.  
  1387.  
  1388. /**@ingroup attribute
  1389.  * Set extended attributes for a file.  This is used for modifying a file's
  1390.  * security descriptor (i.e. owner, group, and access control list).  The
  1391.  * POSIX function which this maps to would act on a symbolic link rather than
  1392.  * acting on what the symbolic link points to, but with no symbolic links in
  1393.  * SMB file systems, this function is functionally identical to
  1394.  * smbc_setxattr().
  1395.  *
  1396.  * @param url       The smb url of the file or directory to set extended
  1397.  *                  attributes for.
  1398.  * 
  1399.  * @param name      The name of an attribute to be changed.  Names are of
  1400.  *                  one of the following forms:
  1401.  *
  1402.  *                     system.nt_sec_desc.<attribute name>
  1403.  *                     system.nt_sec_desc.*
  1404.  *                     system.nt_sec_desc.*+
  1405.  *
  1406.  *                  where <attribute name> is one of:
  1407.  *
  1408.  *                     revision
  1409.  *                     owner
  1410.  *                     owner+
  1411.  *                     group
  1412.  *                     group+
  1413.  *                     acl:<name or sid>
  1414.  *                     acl+:<name or sid>
  1415.  *
  1416.  *                  In the forms "system.nt_sec_desc.*" and
  1417.  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
  1418.  *                  literal, i.e. the string is provided exactly as shown, and
  1419.  *                  the value parameter should contain a complete security
  1420.  *                  descriptor with name:value pairs separated by tabs,
  1421.  *                  commas, or newlines (not spaces!).
  1422.  *
  1423.  *                  The plus sign ('+') indicates that SIDs should be mapped
  1424.  *                  to names.  Without the plus sign, SIDs are not mapped;
  1425.  *                  rather they are simply converted to a string format.
  1426.  *
  1427.  * @param value     The value to be assigned to the specified attribute name.
  1428.  *                  This buffer should contain only the attribute value if the
  1429.  *                  name was of the "system.nt_sec_desc.<attribute_name>"
  1430.  *                  form.  If the name was of the "system.nt_sec_desc.*" form
  1431.  *                  then a complete security descriptor, with name:value pairs
  1432.  *                  separated by tabs, commas, or newlines (not spaces!),
  1433.  *                  should be provided in this value buffer.  A complete
  1434.  *                  security descriptor will contain one or more entries
  1435.  *                  selected from the following:
  1436.  *
  1437.  *                    REVISION:<revision number>
  1438.  *                    OWNER:<sid or name>
  1439.  *                    GROUP:<sid or name>
  1440.  *                    ACL:<sid or name>:<type>/<flags>/<mask>
  1441.  *
  1442.  *                  The  revision of the ACL specifies the internal Windows NT
  1443.  *                  ACL revision for the security descriptor. If not specified
  1444.  *                  it defaults to  1.  Using values other than 1 may cause
  1445.  *                  strange behaviour.
  1446.  *
  1447.  *                  The owner and group specify the owner and group sids for
  1448.  *                  the object. If the attribute name (either '*+' with a
  1449.  *                  complete security descriptor, or individual 'owner+' or
  1450.  *                  'group+' attribute names) ended with a plus sign, the
  1451.  *                  specified name is resolved to a SID value, using the
  1452.  *                  server on which the file or directory resides.  Otherwise,
  1453.  *                  the value should be provided in SID-printable format as
  1454.  *                  S-1-x-y-z, and is used directly.  The <sid or name>
  1455.  *                  associated with the ACL: attribute should be provided
  1456.  *                  similarly.
  1457.  *
  1458.  * @param size      The number of the bytes of data in the value buffer
  1459.  *
  1460.  * @param flags     A bit-wise OR of zero or more of the following:
  1461.  *                    SMBC_XATTR_FLAG_CREATE -
  1462.  *                      fail if the named attribute already exists
  1463.  *                    SMBC_XATTR_FLAG_REPLACE -
  1464.  *                      fail if the attribute does not already exist
  1465.  *
  1466.  *                  If neither flag is specified, the specified attributes
  1467.  *                  will be added or replace existing attributes of the same
  1468.  *                  name, as necessary.
  1469.  *
  1470.  * @return          0 on success, < 0 on error with errno set:
  1471.  *                  - EINVAL  The client library is not properly initialized
  1472.  *                            or one of the parameters is not of a correct
  1473.  *                            form
  1474.  *                  - ENOMEM No memory was available for internal needs
  1475.  *                  - EEXIST  If the attribute already exists and the flag
  1476.  *                            SMBC_XATTR_FLAG_CREAT was specified
  1477.  *                  - ENOATTR If the attribute does not exist and the flag
  1478.  *                            SMBC_XATTR_FLAG_REPLACE was specified
  1479.  *                  - EPERM   Permission was denied.
  1480.  *                  - ENOTSUP The referenced file system does not support
  1481.  *                            extended attributes
  1482.  *
  1483.  * @note            Attribute names are compared in a case-insensitive
  1484.  *                  fashion.  All of the following are equivalent, although
  1485.  *                  the all-lower-case name is the preferred format:
  1486.  *                    system.nt_sec_desc.owner
  1487.  *                    SYSTEM.NT_SEC_DESC.OWNER
  1488.  *                    sYsTeM.nt_sEc_desc.owNER
  1489.  *
  1490.  */
  1491. int smbc_lsetxattr(const char *url,
  1492.                    const char *name,
  1493.                    const void *value,
  1494.                    size_t size,
  1495.                    int flags);
  1496.  
  1497.  
  1498. /**@ingroup attribute
  1499.  * Set extended attributes for a file.  This is used for modifying a file's
  1500.  * security descriptor (i.e. owner, group, and access control list)
  1501.  *
  1502.  * @param fd        A file descriptor associated with an open file (as
  1503.  *                  previously returned by smbc_open(), to get extended
  1504.  *                  attributes for.
  1505.  * 
  1506.  * @param name      The name of an attribute to be changed.  Names are of
  1507.  *                  one of the following forms:
  1508.  *
  1509.  *                     system.nt_sec_desc.<attribute name>
  1510.  *                     system.nt_sec_desc.*
  1511.  *                     system.nt_sec_desc.*+
  1512.  *
  1513.  *                  where <attribute name> is one of:
  1514.  *
  1515.  *                     revision
  1516.  *                     owner
  1517.  *                     owner+
  1518.  *                     group
  1519.  *                     group+
  1520.  *                     acl:<name or sid>
  1521.  *                     acl+:<name or sid>
  1522.  *
  1523.  *                  In the forms "system.nt_sec_desc.*" and
  1524.  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
  1525.  *                  literal, i.e. the string is provided exactly as shown, and
  1526.  *                  the value parameter should contain a complete security
  1527.  *                  descriptor with name:value pairs separated by tabs,
  1528.  *                  commas, or newlines (not spaces!).
  1529.  *
  1530.  *                  The plus sign ('+') indicates that SIDs should be mapped
  1531.  *                  to names.  Without the plus sign, SIDs are not mapped;
  1532.  *                  rather they are simply converted to a string format.
  1533.  *
  1534.  * @param value     The value to be assigned to the specified attribute name.
  1535.  *                  This buffer should contain only the attribute value if the
  1536.  *                  name was of the "system.nt_sec_desc.<attribute_name>"
  1537.  *                  form.  If the name was of the "system.nt_sec_desc.*" form
  1538.  *                  then a complete security descriptor, with name:value pairs
  1539.  *                  separated by tabs, commas, or newlines (not spaces!),
  1540.  *                  should be provided in this value buffer.  A complete
  1541.  *                  security descriptor will contain one or more entries
  1542.  *                  selected from the following:
  1543.  *
  1544.  *                    REVISION:<revision number>
  1545.  *                    OWNER:<sid or name>
  1546.  *                    GROUP:<sid or name>
  1547.  *                    ACL:<sid or name>:<type>/<flags>/<mask>
  1548.  *
  1549.  *                  The  revision of the ACL specifies the internal Windows NT
  1550.  *                  ACL revision for the security descriptor. If not specified
  1551.  *                  it defaults to  1.  Using values other than 1 may cause
  1552.  *                  strange behaviour.
  1553.  *
  1554.  *                  The owner and group specify the owner and group sids for
  1555.  *                  the object. If the attribute name (either '*+' with a
  1556.  *                  complete security descriptor, or individual 'owner+' or
  1557.  *                  'group+' attribute names) ended with a plus sign, the
  1558.  *                  specified name is resolved to a SID value, using the
  1559.  *                  server on which the file or directory resides.  Otherwise,
  1560.  *                  the value should be provided in SID-printable format as
  1561.  *                  S-1-x-y-z, and is used directly.  The <sid or name>
  1562.  *                  associated with the ACL: attribute should be provided
  1563.  *                  similarly.
  1564.  *
  1565.  * @param size      The number of the bytes of data in the value buffer
  1566.  *
  1567.  * @param flags     A bit-wise OR of zero or more of the following:
  1568.  *                    SMBC_XATTR_FLAG_CREATE -
  1569.  *                      fail if the named attribute already exists
  1570.  *                    SMBC_XATTR_FLAG_REPLACE -
  1571.  *                      fail if the attribute does not already exist
  1572.  *
  1573.  *                  If neither flag is specified, the specified attributes
  1574.  *                  will be added or replace existing attributes of the same
  1575.  *                  name, as necessary.
  1576.  *
  1577.  * @return          0 on success, < 0 on error with errno set:
  1578.  *                  - EINVAL  The client library is not properly initialized
  1579.  *                            or one of the parameters is not of a correct
  1580.  *                            form
  1581.  *                  - ENOMEM No memory was available for internal needs
  1582.  *                  - EEXIST  If the attribute already exists and the flag
  1583.  *                            SMBC_XATTR_FLAG_CREAT was specified
  1584.  *                  - ENOATTR If the attribute does not exist and the flag
  1585.  *                            SMBC_XATTR_FLAG_REPLACE was specified
  1586.  *                  - EPERM   Permission was denied.
  1587.  *                  - ENOTSUP The referenced file system does not support
  1588.  *                            extended attributes
  1589.  *
  1590.  * @note            Attribute names are compared in a case-insensitive
  1591.  *                  fashion.  All of the following are equivalent, although
  1592.  *                  the all-lower-case name is the preferred format:
  1593.  *                    system.nt_sec_desc.owner
  1594.  *                    SYSTEM.NT_SEC_DESC.OWNER
  1595.  *                    sYsTeM.nt_sEc_desc.owNER
  1596.  *
  1597.  */
  1598. int smbc_fsetxattr(int fd,
  1599.                    const char *name,
  1600.                    const void *value,
  1601.                    size_t size,
  1602.                    int flags);
  1603.  
  1604.  
  1605. /**@ingroup attribute
  1606.  * Get extended attributes for a file.
  1607.  *
  1608.  * @param url       The smb url of the file or directory to get extended
  1609.  *                  attributes for.
  1610.  * 
  1611.  * @param name      The name of an attribute to be retrieved.  Names are of
  1612.  *                  one of the following forms:
  1613.  *
  1614.  *                     system.nt_sec_desc.<attribute name>
  1615.  *                     system.nt_sec_desc.*
  1616.  *                     system.nt_sec_desc.*+
  1617.  *
  1618.  *                  where <attribute name> is one of:
  1619.  *
  1620.  *                     revision
  1621.  *                     owner
  1622.  *                     owner+
  1623.  *                     group
  1624.  *                     group+
  1625.  *                     acl:<name or sid>
  1626.  *                     acl+:<name or sid>
  1627.  *
  1628.  *                  In the forms "system.nt_sec_desc.*" and
  1629.  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
  1630.  *                  literal, i.e. the string is provided exactly as shown, and
  1631.  *                  the value parameter will return a complete security
  1632.  *                  descriptor with name:value pairs separated by tabs,
  1633.  *                  commas, or newlines (not spaces!).
  1634.  *
  1635.  *                  The plus sign ('+') indicates that SIDs should be mapped
  1636.  *                  to names.  Without the plus sign, SIDs are not mapped;
  1637.  *                  rather they are simply converted to a string format.
  1638.  *
  1639.  * @param value     A pointer to a buffer in which the value of the specified
  1640.  *                  attribute will be placed (unless size is zero).
  1641.  *
  1642.  * @param size      The size of the buffer pointed to by value.  This parameter
  1643.  *                  may also be zero, in which case the size of the buffer
  1644.  *                  required to hold the attribute value will be returned,
  1645.  *                  but nothing will be placed into the value buffer.
  1646.  * 
  1647.  * @return          0 on success, < 0 on error with errno set:
  1648.  *                  - EINVAL  The client library is not properly initialized
  1649.  *                            or one of the parameters is not of a correct
  1650.  *                            form
  1651.  *                  - ENOMEM No memory was available for internal needs
  1652.  *                  - EEXIST  If the attribute already exists and the flag
  1653.  *                            SMBC_XATTR_FLAG_CREAT was specified
  1654.  *                  - ENOATTR If the attribute does not exist and the flag
  1655.  *                            SMBC_XATTR_FLAG_REPLACE was specified
  1656.  *                  - EPERM   Permission was denied.
  1657.  *                  - ENOTSUP The referenced file system does not support
  1658.  *                            extended attributes
  1659.  *
  1660.  */
  1661. int smbc_getxattr(const char *url,
  1662.                   const char *name,
  1663.                   const void *value,
  1664.                   size_t size);
  1665.  
  1666.  
  1667. /**@ingroup attribute
  1668.  * Get extended attributes for a file.  The POSIX function which this maps to
  1669.  * would act on a symbolic link rather than acting on what the symbolic link
  1670.  * points to, but with no symbolic links in SMB file systems, this function
  1671.  * is functionally identical to smbc_getxattr().
  1672.  *
  1673.  * @param url       The smb url of the file or directory to get extended
  1674.  *                  attributes for.
  1675.  * 
  1676.  * @param name      The name of an attribute to be retrieved.  Names are of
  1677.  *                  one of the following forms:
  1678.  *
  1679.  *                     system.nt_sec_desc.<attribute name>
  1680.  *                     system.nt_sec_desc.*
  1681.  *                     system.nt_sec_desc.*+
  1682.  *
  1683.  *                  where <attribute name> is one of:
  1684.  *
  1685.  *                     revision
  1686.  *                     owner
  1687.  *                     owner+
  1688.  *                     group
  1689.  *                     group+
  1690.  *                     acl:<name or sid>
  1691.  *                     acl+:<name or sid>
  1692.  *
  1693.  *                  In the forms "system.nt_sec_desc.*" and
  1694.  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
  1695.  *                  literal, i.e. the string is provided exactly as shown, and
  1696.  *                  the value parameter will return a complete security
  1697.  *                  descriptor with name:value pairs separated by tabs,
  1698.  *                  commas, or newlines (not spaces!).
  1699.  *
  1700.  *                  The plus sign ('+') indicates that SIDs should be mapped
  1701.  *                  to names.  Without the plus sign, SIDs are not mapped;
  1702.  *                  rather they are simply converted to a string format.
  1703.  *
  1704.  * @param value     A pointer to a buffer in which the value of the specified
  1705.  *                  attribute will be placed (unless size is zero).
  1706.  *
  1707.  * @param size      The size of the buffer pointed to by value.  This parameter
  1708.  *                  may also be zero, in which case the size of the buffer
  1709.  *                  required to hold the attribute value will be returned,
  1710.  *                  but nothing will be placed into the value buffer.
  1711.  * 
  1712.  * @return          0 on success, < 0 on error with errno set:
  1713.  *                  - EINVAL  The client library is not properly initialized
  1714.  *                            or one of the parameters is not of a correct
  1715.  *                            form
  1716.  *                  - ENOMEM No memory was available for internal needs
  1717.  *                  - EEXIST  If the attribute already exists and the flag
  1718.  *                            SMBC_XATTR_FLAG_CREAT was specified
  1719.  *                  - ENOATTR If the attribute does not exist and the flag
  1720.  *                            SMBC_XATTR_FLAG_REPLACE was specified
  1721.  *                  - EPERM   Permission was denied.
  1722.  *                  - ENOTSUP The referenced file system does not support
  1723.  *                            extended attributes
  1724.  *
  1725.  */
  1726. int smbc_lgetxattr(const char *url,
  1727.                    const char *name,
  1728.                    const void *value,
  1729.                    size_t size);
  1730.  
  1731.  
  1732. /**@ingroup attribute
  1733.  * Get extended attributes for a file.
  1734.  *
  1735.  * @param fd        A file descriptor associated with an open file (as
  1736.  *                  previously returned by smbc_open(), to get extended
  1737.  *                  attributes for.
  1738.  * 
  1739.  * @param name      The name of an attribute to be retrieved.  Names are of
  1740.  *                  one of the following forms:
  1741.  *
  1742.  *                     system.nt_sec_desc.<attribute name>
  1743.  *                     system.nt_sec_desc.*
  1744.  *                     system.nt_sec_desc.*+
  1745.  *
  1746.  *                  where <attribute name> is one of:
  1747.  *
  1748.  *                     revision
  1749.  *                     owner
  1750.  *                     owner+
  1751.  *                     group
  1752.  *                     group+
  1753.  *                     acl:<name or sid>
  1754.  *                     acl+:<name or sid>
  1755.  *
  1756.  *                  In the forms "system.nt_sec_desc.*" and
  1757.  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
  1758.  *                  literal, i.e. the string is provided exactly as shown, and
  1759.  *                  the value parameter will return a complete security
  1760.  *                  descriptor with name:value pairs separated by tabs,
  1761.  *                  commas, or newlines (not spaces!).
  1762.  *
  1763.  *                  The plus sign ('+') indicates that SIDs should be mapped
  1764.  *                  to names.  Without the plus sign, SIDs are not mapped;
  1765.  *                  rather they are simply converted to a string format.
  1766.  *
  1767.  * @param value     A pointer to a buffer in which the value of the specified
  1768.  *                  attribute will be placed (unless size is zero).
  1769.  *
  1770.  * @param size      The size of the buffer pointed to by value.  This parameter
  1771.  *                  may also be zero, in which case the size of the buffer
  1772.  *                  required to hold the attribute value will be returned,
  1773.  *                  but nothing will be placed into the value buffer.
  1774.  * 
  1775.  * @return          0 on success, < 0 on error with errno set:
  1776.  *                  - EINVAL  The client library is not properly initialized
  1777.  *                            or one of the parameters is not of a correct
  1778.  *                            form
  1779.  *                  - ENOMEM No memory was available for internal needs
  1780.  *                  - EEXIST  If the attribute already exists and the flag
  1781.  *                            SMBC_XATTR_FLAG_CREAT was specified
  1782.  *                  - ENOATTR If the attribute does not exist and the flag
  1783.  *                            SMBC_XATTR_FLAG_REPLACE was specified
  1784.  *                  - EPERM   Permission was denied.
  1785.  *                  - ENOTSUP The referenced file system does not support
  1786.  *                            extended attributes
  1787.  *
  1788.  */
  1789. int smbc_fgetxattr(int fd,
  1790.                    const char *name,
  1791.                    const void *value,
  1792.                    size_t size);
  1793.  
  1794.  
  1795. /**@ingroup attribute
  1796.  * Remove extended attributes for a file.  This is used for modifying a file's
  1797.  * security descriptor (i.e. owner, group, and access control list)
  1798.  *
  1799.  * @param url       The smb url of the file or directory to remove the extended
  1800.  *                  attributes for.
  1801.  * 
  1802.  * @param name      The name of an attribute to be removed.  Names are of
  1803.  *                  one of the following forms:
  1804.  *
  1805.  *                     system.nt_sec_desc.<attribute name>
  1806.  *                     system.nt_sec_desc.*
  1807.  *                     system.nt_sec_desc.*+
  1808.  *
  1809.  *                  where <attribute name> is one of:
  1810.  *
  1811.  *                     revision
  1812.  *                     owner
  1813.  *                     owner+
  1814.  *                     group
  1815.  *                     group+
  1816.  *                     acl:<name or sid>
  1817.  *                     acl+:<name or sid>
  1818.  *
  1819.  *                  In the forms "system.nt_sec_desc.*" and
  1820.  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
  1821.  *                  literal, i.e. the string is provided exactly as shown, and
  1822.  *                  the value parameter will return a complete security
  1823.  *                  descriptor with name:value pairs separated by tabs,
  1824.  *                  commas, or newlines (not spaces!).
  1825.  *
  1826.  *                  The plus sign ('+') indicates that SIDs should be mapped
  1827.  *                  to names.  Without the plus sign, SIDs are not mapped;
  1828.  *                  rather they are simply converted to a string format.
  1829.  *
  1830.  * @return          0 on success, < 0 on error with errno set:
  1831.  *                  - EINVAL The client library is not properly initialized
  1832.  *                  - ENOMEM No memory was available for internal needs
  1833.  *                  - EPERM  Permission was denied.
  1834.  *                  - ENOTSUP The referenced file system does not support
  1835.  *                            extended attributes
  1836.  *
  1837.  */
  1838. int smbc_removexattr(const char *url,
  1839.                      const char *name);
  1840.  
  1841.  
  1842. /**@ingroup attribute
  1843.  * Remove extended attributes for a file.  This is used for modifying a file's
  1844.  * security descriptor (i.e. owner, group, and access control list) The POSIX
  1845.  * function which this maps to would act on a symbolic link rather than acting
  1846.  * on what the symbolic link points to, but with no symbolic links in SMB file
  1847.  * systems, this function is functionally identical to smbc_removexattr().
  1848.  *
  1849.  * @param url       The smb url of the file or directory to remove the extended
  1850.  *                  attributes for.
  1851.  * 
  1852.  * @param name      The name of an attribute to be removed.  Names are of
  1853.  *                  one of the following forms:
  1854.  *
  1855.  *                     system.nt_sec_desc.<attribute name>
  1856.  *                     system.nt_sec_desc.*
  1857.  *                     system.nt_sec_desc.*+
  1858.  *
  1859.  *                  where <attribute name> is one of:
  1860.  *
  1861.  *                     revision
  1862.  *                     owner
  1863.  *                     owner+
  1864.  *                     group
  1865.  *                     group+
  1866.  *                     acl:<name or sid>
  1867.  *                     acl+:<name or sid>
  1868.  *
  1869.  *                  In the forms "system.nt_sec_desc.*" and
  1870.  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
  1871.  *                  literal, i.e. the string is provided exactly as shown, and
  1872.  *                  the value parameter will return a complete security
  1873.  *                  descriptor with name:value pairs separated by tabs,
  1874.  *                  commas, or newlines (not spaces!).
  1875.  *
  1876.  *                  The plus sign ('+') indicates that SIDs should be mapped
  1877.  *                  to names.  Without the plus sign, SIDs are not mapped;
  1878.  *                  rather they are simply converted to a string format.
  1879.  *
  1880.  * @return          0 on success, < 0 on error with errno set:
  1881.  *                  - EINVAL The client library is not properly initialized
  1882.  *                  - ENOMEM No memory was available for internal needs
  1883.  *                  - EPERM  Permission was denied.
  1884.  *                  - ENOTSUP The referenced file system does not support
  1885.  *                            extended attributes
  1886.  *
  1887.  */
  1888. int smbc_lremovexattr(const char *url,
  1889.                       const char *name);
  1890.  
  1891.  
  1892. /**@ingroup attribute
  1893.  * Remove extended attributes for a file.  This is used for modifying a file's
  1894.  * security descriptor (i.e. owner, group, and access control list)
  1895.  *
  1896.  * @param fd        A file descriptor associated with an open file (as
  1897.  *                  previously returned by smbc_open(), to get extended
  1898.  *                  attributes for.
  1899.  * 
  1900.  * @param name      The name of an attribute to be removed.  Names are of
  1901.  *                  one of the following forms:
  1902.  *
  1903.  *                     system.nt_sec_desc.<attribute name>
  1904.  *                     system.nt_sec_desc.*
  1905.  *                     system.nt_sec_desc.*+
  1906.  *
  1907.  *                  where <attribute name> is one of:
  1908.  *
  1909.  *                     revision
  1910.  *                     owner
  1911.  *                     owner+
  1912.  *                     group
  1913.  *                     group+
  1914.  *                     acl:<name or sid>
  1915.  *                     acl+:<name or sid>
  1916.  *
  1917.  *                  In the forms "system.nt_sec_desc.*" and
  1918.  *                  "system.nt_sec_desc.*+", the asterisk and plus signs are
  1919.  *                  literal, i.e. the string is provided exactly as shown, and
  1920.  *                  the value parameter will return a complete security
  1921.  *                  descriptor with name:value pairs separated by tabs,
  1922.  *                  commas, or newlines (not spaces!).
  1923.  *
  1924.  *                  The plus sign ('+') indicates that SIDs should be mapped
  1925.  *                  to names.  Without the plus sign, SIDs are not mapped;
  1926.  *                  rather they are simply converted to a string format.
  1927.  *
  1928.  * @return          0 on success, < 0 on error with errno set:
  1929.  *                  - EINVAL The client library is not properly initialized
  1930.  *                  - ENOMEM No memory was available for internal needs
  1931.  *                  - EPERM  Permission was denied.
  1932.  *                  - ENOTSUP The referenced file system does not support
  1933.  *                            extended attributes
  1934.  *
  1935.  */
  1936. int smbc_fremovexattr(int fd,
  1937.                       const char *name);
  1938.  
  1939.  
  1940. /**@ingroup attribute
  1941.  * List the supported extended attribute names associated with a file
  1942.  *
  1943.  * @param url       The smb url of the file or directory to list the extended
  1944.  *                  attributes for.
  1945.  *
  1946.  * @param list      A pointer to a buffer in which the list of attributes for
  1947.  *                  the specified file or directory will be placed (unless
  1948.  *                  size is zero).
  1949.  *
  1950.  * @param size      The size of the buffer pointed to by list.  This parameter
  1951.  *                  may also be zero, in which case the size of the buffer
  1952.  *                  required to hold all of the attribute names will be
  1953.  *                  returned, but nothing will be placed into the list buffer.
  1954.  * 
  1955.  * @return          0 on success, < 0 on error with errno set:
  1956.  *                  - EINVAL The client library is not properly initialized
  1957.  *                  - ENOMEM No memory was available for internal needs
  1958.  *                  - EPERM  Permission was denied.
  1959.  *                  - ENOTSUP The referenced file system does not support
  1960.  *                            extended attributes
  1961.  *
  1962.  * @note            This function always returns all attribute names supported
  1963.  *                  by NT file systems, regardless of wether the referenced
  1964.  *                  file system supports extended attributes (e.g. a Windows
  1965.  *                  2000 machine supports extended attributes if NTFS is used,
  1966.  *                  but not if FAT is used, and Windows 98 doesn't support
  1967.  *                  extended attributes at all.  Whether this is a feature or
  1968.  *                  a bug is yet to be decided.
  1969.  */
  1970. int smbc_listxattr(const char *url,
  1971.                    char *list,
  1972.                    size_t size);
  1973.  
  1974. /**@ingroup attribute
  1975.  * List the supported extended attribute names associated with a file The
  1976.  * POSIX function which this maps to would act on a symbolic link rather than
  1977.  * acting on what the symbolic link points to, but with no symbolic links in
  1978.  * SMB file systems, this function is functionally identical to
  1979.  * smbc_listxattr().
  1980.  *
  1981.  * @param url       The smb url of the file or directory to list the extended
  1982.  *                  attributes for.
  1983.  *
  1984.  * @param list      A pointer to a buffer in which the list of attributes for
  1985.  *                  the specified file or directory will be placed (unless
  1986.  *                  size is zero).
  1987.  *
  1988.  * @param size      The size of the buffer pointed to by list.  This parameter
  1989.  *                  may also be zero, in which case the size of the buffer
  1990.  *                  required to hold all of the attribute names will be
  1991.  *                  returned, but nothing will be placed into the list buffer.
  1992.  * 
  1993.  * @return          0 on success, < 0 on error with errno set:
  1994.  *                  - EINVAL The client library is not properly initialized
  1995.  *                  - ENOMEM No memory was available for internal needs
  1996.  *                  - EPERM  Permission was denied.
  1997.  *                  - ENOTSUP The referenced file system does not support
  1998.  *                            extended attributes
  1999.  *
  2000.  * @note            This function always returns all attribute names supported
  2001.  *                  by NT file systems, regardless of wether the referenced
  2002.  *                  file system supports extended attributes (e.g. a Windows
  2003.  *                  2000 machine supports extended attributes if NTFS is used,
  2004.  *                  but not if FAT is used, and Windows 98 doesn't support
  2005.  *                  extended attributes at all.  Whether this is a feature or
  2006.  *                  a bug is yet to be decided.
  2007.  */
  2008. int smbc_llistxattr(const char *url,
  2009.                     char *list,
  2010.                     size_t size);
  2011.  
  2012. /**@ingroup attribute
  2013.  * List the supported extended attribute names associated with a file
  2014.  *
  2015.  * @param fd        A file descriptor associated with an open file (as
  2016.  *                  previously returned by smbc_open(), to get extended
  2017.  *                  attributes for.
  2018.  * 
  2019.  * @param list      A pointer to a buffer in which the list of attributes for
  2020.  *                  the specified file or directory will be placed (unless
  2021.  *                  size is zero).
  2022.  *
  2023.  * @param size      The size of the buffer pointed to by list.  This parameter
  2024.  *                  may also be zero, in which case the size of the buffer
  2025.  *                  required to hold all of the attribute names will be
  2026.  *                  returned, but nothing will be placed into the list buffer.
  2027.  * 
  2028.  * @return          0 on success, < 0 on error with errno set:
  2029.  *                  - EINVAL The client library is not properly initialized
  2030.  *                  - ENOMEM No memory was available for internal needs
  2031.  *                  - EPERM  Permission was denied.
  2032.  *                  - ENOTSUP The referenced file system does not support
  2033.  *                            extended attributes
  2034.  *
  2035.  * @note            This function always returns all attribute names supported
  2036.  *                  by NT file systems, regardless of wether the referenced
  2037.  *                  file system supports extended attributes (e.g. a Windows
  2038.  *                  2000 machine supports extended attributes if NTFS is used,
  2039.  *                  but not if FAT is used, and Windows 98 doesn't support
  2040.  *                  extended attributes at all.  Whether this is a feature or
  2041.  *                  a bug is yet to be decided.
  2042.  */
  2043. int smbc_flistxattr(int fd,
  2044.                     char *list,
  2045.                     size_t size);
  2046.  
  2047. /**@ingroup print
  2048.  * Print a file given the name in fname. It would be a URL ...
  2049.  * 
  2050.  * @param fname     The URL of a file on a remote SMB server that the
  2051.  *                  caller wants printed
  2052.  *
  2053.  * @param printq    The URL of the print share to print the file to.
  2054.  *
  2055.  * @return          0 on success, < 0 on error with errno set:         
  2056.  *
  2057.  *                  - EINVAL fname or printq was NULL or smbc_init not
  2058.  *               not called.
  2059.  *                  and errors returned by smbc_open
  2060.  *
  2061.  */                                     
  2062. int smbc_print_file(const char *fname, const char *printq);
  2063.  
  2064. /**@ingroup print
  2065.  * Open a print file that can be written to by other calls. This simply
  2066.  * does an smbc_open call after checking if there is a file name on the
  2067.  * URI. If not, a temporary name is added ...
  2068.  *
  2069.  * @param fname     The URL of the print share to print to?
  2070.  *
  2071.  * @returns         A file handle for the print file if successful.
  2072.  *                  Returns -1 if an error ocurred and errno has the values
  2073.  *                  - EINVAL fname was NULL or smbc_init not called.
  2074.  *                  - all errors returned by smbc_open
  2075.  *
  2076.  */
  2077. int smbc_open_print_job(const char *fname);
  2078.  
  2079. /**@ingroup print
  2080.  * List the print jobs on a print share, for the moment, pass a callback 
  2081.  *
  2082.  * @param purl      The url of the print share to list the jobs of
  2083.  * 
  2084.  * @param fn        Callback function the receives printjob info
  2085.  * 
  2086.  * @return          0 on success, < 0 on error with errno set: 
  2087.  *                  - EINVAL fname was NULL or smbc_init not called
  2088.  *                  - EACCES ???
  2089.  */
  2090. int smbc_list_print_jobs(const char *purl, smbc_list_print_job_fn fn);
  2091.  
  2092. /**@ingroup print
  2093.  * Delete a print job 
  2094.  *
  2095.  * @param purl      Url of the print share
  2096.  *
  2097.  * @param id        The id of the job to delete
  2098.  *
  2099.  * @return          0 on success, < 0 on error with errno set: 
  2100.  *                  - EINVAL fname was NULL or smbc_init not called
  2101.  *
  2102.  * @todo    what errno values are possible here?
  2103.  */
  2104. int smbc_unlink_print_job(const char *purl, int id);
  2105.  
  2106. /**@ingroup callback
  2107.  * Remove a server from the cached server list it's unused.
  2108.  *
  2109.  * @param context    pointer to smb context
  2110.  *
  2111.  * @param srv        pointer to server to remove
  2112.  *
  2113.  * @return On success, 0 is returned. 1 is returned if the server could not
  2114.  *         be removed. Also useable outside libsmbclient.
  2115.  */
  2116. int smbc_remove_unused_server(SMBCCTX * context, SMBCSRV * srv);
  2117.  
  2118. #ifdef __cplusplus
  2119. }
  2120. #endif
  2121.  
  2122. /**@ingroup directory
  2123.  * Convert strings of %xx to their single character equivalent.
  2124.  *
  2125.  * @param dest      A pointer to a buffer in which the resulting decoded
  2126.  *                  string should be placed.  This may be a pointer to the
  2127.  *                  same buffer as src_segment.
  2128.  * 
  2129.  * @param src       A pointer to the buffer containing the URL to be decoded.
  2130.  *                  Any %xx sequences herein are converted to their single
  2131.  *                  character equivalent.  Each 'x' must be a valid hexadecimal
  2132.  *                  digit, or that % sequence is left undecoded.
  2133.  *
  2134.  * @param max_dest_len
  2135.  *                  The size of the buffer pointed to by dest_segment.
  2136.  * 
  2137.  * @return          The number of % sequences which could not be converted
  2138.  *                  due to lack of two following hexadecimal digits.
  2139.  */
  2140. #ifdef __cplusplus
  2141. extern "C" {
  2142. #endif
  2143. int
  2144. smbc_urldecode(char *dest, char * src, size_t max_dest_len);
  2145. #ifdef __cplusplus
  2146. }
  2147. #endif
  2148.  
  2149.  
  2150. /*
  2151.  * Convert any characters not specifically allowed in a URL into their %xx
  2152.  * equivalent.
  2153.  *
  2154.  * @param dest      A pointer to a buffer in which the resulting encoded
  2155.  *                  string should be placed.  Unlike smbc_urldecode(), this
  2156.  *                  must be a buffer unique from src.
  2157.  * 
  2158.  * @param src       A pointer to the buffer containing the string to be encoded.
  2159.  *                  Any character not specifically allowed in a URL is converted
  2160.  *                  into its hexadecimal value and encoded as %xx.
  2161.  *
  2162.  * @param max_dest_len
  2163.  *                  The size of the buffer pointed to by dest_segment.
  2164.  * 
  2165.  * @returns         The remaining buffer length.
  2166.  */
  2167. #ifdef __cplusplus
  2168. extern "C" {
  2169. #endif
  2170. int
  2171. smbc_urlencode(char * dest, char * src, int max_dest_len);
  2172. #ifdef __cplusplus
  2173. }
  2174. #endif
  2175.  
  2176.  
  2177. /**@ingroup directory
  2178.  * Return the version of the linked Samba code, and thus the version of the
  2179.  * libsmbclient code.
  2180.  *
  2181.  * @return          The version string.
  2182.  */
  2183. #ifdef __cplusplus
  2184. extern "C" {
  2185. #endif
  2186. const char *
  2187. smbc_version(void);
  2188. #ifdef __cplusplus
  2189. }
  2190. #endif
  2191.  
  2192.  
  2193. #endif /* SMBCLIENT_H_INCLUDED */
  2194.